home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac 1993 September / September 93.iso / Archives / Sound / Playing & Recording / Macintosh Tracker / Tracker AEIMP Protocol < prev    next >
Encoding:
Text File  |  1993-06-09  |  7.6 KB  |  182 lines  |  [TEXT/KAHL]
  1. Description of Tracker protocol:
  2.  
  3.  
  4. The Interface program controls the Servers through the use of
  5. Apple Events.  The following document describes how to use the
  6. controls so that either the Server of the Interface may be replaced.
  7.  
  8. In my terminology,
  9. Interface:  The program used to select the songs to play.
  10. Server:  The small program that actually plays the song.
  11.  
  12. Note that #define's for many of the values here can be found in
  13. the file "mac_events.h" which you can simply lift out and put into
  14. your own files.
  15.  
  16.  
  17.  
  18. Starting the Server:
  19.  
  20. The server is launched with an extended Open Document Apple Event.
  21. The event should contain one (1) file specification describing which
  22. song to open, in the normal Open Document way.  When launched, the
  23. server should continually call WaitNextEvent, waiting for the Open
  24. Event.  It should also be aware that a Quit Event might come at
  25. this point.
  26.  
  27. In addition to the required parameter, there are several
  28. additional parameters which describe the options to be used to
  29. play back the song:
  30.  
  31. Key Word         Code    Type
  32. -----------------------------------------------------------------------------------
  33. keyAntiAliasing  '∫Saa'  typeShortInteger
  34.   Boolean flag:  1 = use antialiasing algorithm, 0 = use fast algorithm
  35.  
  36. keyStereoOn      '∫Sso'  typeShortInteger
  37.   Boolean flag:  1 = use stereo playback, 0 = use mono playback
  38.  
  39. keySamplingRate  '∫Ssr'  typeShortInteger
  40.   Integer part of sampling rate in Hertz.  Should be converted to an unsigned
  41.   16-bit integer upon receipt, and then treated however your program needs to.
  42.   (Usually shifted left by 16 to create a Fixed type for the Sound Manager.)
  43.  
  44. keyNumRepeats    '∫Snr'  typeShortInteger
  45.   The number of times to repeat the song.  0 = repeat indefinitely, 1 = repeat once.
  46.   2 and up means repeat that many times.
  47.  
  48. keySpeed         '∫Ssp'  typeShortInteger
  49.   The speed in the number of ProTracker frames per second.  Usually, this is 50.
  50.  
  51. keyStereoMix     '∫Ssm'  typeShortInteger
  52.   How to mix for stereo.  0 is no mixing (hard separation), 100 is full mixing (mono).
  53.   Any number in between can be sent, but do not send negative numbers or numbers
  54.   that exceed 100.
  55.  
  56. keyLoudness      '∫Svl'  typeShortInteger
  57.   Value indicating loudness to play song at.  Generally, 0 is silence, and 64 is
  58.   the maximum value.  You may go as high as 255, so the tracker should constrain
  59.   the volume at 64 if it can't handle values greater than 64.  Negative values or
  60.   values greater than 255 should never be passed.
  61.  
  62. keySenderPSN     '∫Psn'  typeProcessSerialNumber
  63.   Process serial number of the launching process.  This is used to send error
  64.   messages back to the launching process.
  65.  
  66. If these parameters are missing, the tracker should supply reasonable
  67. defaults.  This might happen if the user drags a song onto the tracker
  68. from the Finder.
  69.  
  70.  
  71.  
  72. Control Event:  Changing settings "on the fly."
  73.  
  74. The control event is a custom event.  The Event Class is '∫Tsp' and the
  75. Event Type is '∫Ctl'.  This event may contain any of the following parameters
  76. to be acted upon as soon as possible.
  77.  
  78. Key Word              Code    Type
  79. -----------------------------------------------------------------------------------
  80. keyAntiAliasing       '∫Saa'  typeShortInteger
  81. keyStereoOn           '∫Sso'  typeShortInteger
  82. keySamplingRate       '∫Ssr'  typeShortInteger
  83. keyNumRepeats         '∫Snr'  typeShortInteger
  84. keySpeed              '∫Ssp'  typeShortInteger
  85. keyStereoMix          '∫Ssm'  typeShortInteger
  86. keyLoudness           '∫Svl'  typeShortInteger
  87.  
  88. keyKeyPressCharacter  '∫Key'  typeShortInteger
  89.  
  90. All of the parameters which can also occur in the Open Document event have
  91. the same meaning here as they do in the Open Document event.
  92.  
  93. The KeyPress event originally faked keypresses to Espie's Tracker running it's
  94. unaltered UNIX interface behind the scenes.  That's how it got its name.
  95. However, it has changed to support general interactive control.
  96.  
  97. Usually, the parameter is interpreted as a character.  The following
  98. characters are currently supported:
  99.  
  100.   Character   Description
  101.   --------------------------------------------------------------
  102.   '>'         Fast Forward Begin
  103.     This indicates that the tracker should begin fast forwarding.  It is
  104.     sent when the user presses the mouse button DOWN in the fast forward
  105.     control.  The program should continue to fast forward the song until
  106.     notified otherwise.
  107.  
  108.   '<'         Rewind Begin
  109.     Rewind was originally intended to run the song backwards.  However, this
  110.     is nearly impossible, so currently it restarts the song.  In theory, the
  111.     program should continue to rewind until notified otherwise, so be
  112.     prepared to receive the normal play command (described next).
  113.  
  114.   '|'         Return to Normal Play (i.e. Cancel Fast Forward or Rewind)
  115.     This is sent when the user releases the mouse button from the rewind or
  116.     fast forward control.  If you are fast forwarding, resume normal tempo.
  117.     If you are not fast forwarding (then you probably got a rewind command)
  118.     just ignore it, but be prepared for it.
  119.  
  120.   '+'         Increase Loudness
  121.     Increase the volume a bit.  This isn't too important.
  122.  
  123.   '-'         Decrease Loudness
  124.     Likewise.
  125.  
  126.  
  127.  
  128. Returning Error Messages to the Launcher:
  129.  
  130. If the Server runs out of memory, encounters a really bad error, can't
  131. play the song, or something else happens, this event should be sent back
  132. to the Interface so that an alert can be presented to the user.
  133.  
  134. Note that these error messages describe FATAL errors.  Therefore, only one
  135. error should ever be sent per song and the tracker Server should exit
  136. immediately after sending the event.
  137.  
  138. The Event Class is '∫Tsp' and the Event ID is '∫Err'.  It contains one
  139. parameter of keyword '∫Er#' and type typeShortInteger.  Pass the following
  140. values for whichever error applies.
  141.  
  142. 0:  An unknown error occured.
  143. 1:  Server ran out of memory loading the song or setting up the buffers.
  144. 2:  An internal error occurred (generic "catch-all" type of error).
  145. 3:  Server can't open compressed files.  This is in here because Marc Espies's
  146.     Tracker will automatically pipe files through their appropriate decompressors
  147.     if there is an extention like ".zip" or ".Z".  Since the Macintosh doesn't
  148.     support pipes, the function "popen" sends this error.  Tell the user to
  149.     rename the file so that it doesn't have the extention any more.
  150.     As a side note:  I've modified the way I call Espie's main(argc,argv)
  151.     routine, so if "Tracker Server" ever sends this error, it is indicative
  152.     of a serious malfunction of the program.  I would suggest avoiding
  153.     using this error message for anything in your own Servers.
  154. 4:  The Server couldn't open the file.  This can be sent whenever the file can't
  155.     be open, for whatever reason that might be (file table full, too many
  156.     open working directories, etc...)
  157. 5:  Server Could't close file.  This will probably never happen, but it's in here
  158.     just in case.
  159. 6:  Server was told to open a file that isn't a song.  You should send this, but
  160.     you'll notice I haven't hacked Espie's calls to perror() and printf() to check
  161.     for his message "Not a song", so obviously it's not a high priority on
  162.     my list!
  163. 7:    68020 processor required.
  164.  
  165.  
  166.  
  167. What to do when the song is finished:
  168.  
  169. Just exit!  The Finder will automatically send the Interface an 'OBIT' event
  170. (Application Died) which the Interface should then interpret to mean it can
  171. start the next song or do whatever operation is called for.
  172.  
  173.  
  174.  
  175. Quit Events:
  176.  
  177. When the user cancels a song or shuts down the computer, a standard Quit Event
  178. is sent to the tracker program.  It should stop sound production, immediately
  179. dispose of any precomputed buffers, close sound channels, and exit.  This should
  180. all be done as soon as possible to prevent sluggishness.
  181.  
  182.